ShowTable of Contents
Data API lowercasefields parameter
The document resource GET operation now supports a lowercasefields parameter. This can help an API client resolve JSON case sensitivity issues.
Suppose you send a GET request to this URL:
/xpagesext.nsf/api/data/documents/unid/39A95ECD82D0DEB485257AB5005BFEE0
The response might include mixed case field names like this:
{
"@href": "/xpagesext.nsf/api/data/documents/unid/39A95ECD82D0DEB485257AB5005BFEE0",
"@unid": "39A95ECD82D0DEB485257AB5005BFEE0",
"@noteid": "5D26",
"@created": "2012-11-13T16:44:50Z",
"@modified": "2013-07-16T21:39:28Z",
"@form": "Contact",
"Id": "CN=Aaron Goodman/O=renovations",
"FirstName": "Aaron",
"LastName": "Goodman",
"City": "Philadelphia",
"State": "PA",
"EMail": "aaron_goodman@renovations.com"
}
Notice how FirstName and LastName are mixed case. However, because Notes and Domino item names are not case sensitive, the case may change from one document to the next. To force all JSON property names to lower case, you can instead use this URL:
/xpagesext.nsf/api/data/documents/unid/39A95ECD82D0DEB485257AB5005BFEE0?lowercasefields=true
Now the response will look like this:
{
"@href": "/xpagesext.nsf/api/data/documents/unid/39A95ECD82D0DEB485257AB5005BFEE0",
"@unid": "39A95ECD82D0DEB485257AB5005BFEE0",
"@noteid": "5D26",
"@created": "2012-11-13T16:44:50Z",
"@modified": "2013-07-16T21:39:28Z",
"@form": "Contact",
"id": "CN=Aaron Goodman/O=renovations",
"firstname": "Aaron",
"lastname": "Goodman",
"city": "Philadelphia",
"state": "PA",
"email": "aaron_goodman@renovations.com"
}
Data API fields parameter
The document resource GET operation now supports a fields parameter. This can help an API client improve performance by limiting the size of the response.
Again, suppose you send a GET request to this URL:
/xpagesext.nsf/api/data/documents/unid/39A95ECD82D0DEB485257AB5005BFEE0
The response might include several application-specific field names like Id, FirstName, LastName, City, State and EMail:
{
"@href": "/xpagesext.nsf/api/data/documents/unid/39A95ECD82D0DEB485257AB5005BFEE0",
"@unid": "39A95ECD82D0DEB485257AB5005BFEE0",
"@noteid": "5D26",
"@created": "2012-11-13T16:44:50Z",
"@modified": "2013-07-16T21:39:28Z",
"@form": "Contact",
"Id": "CN=Aaron Goodman/O=renovations",
"FirstName": "Aaron",
"LastName": "Goodman",
"City": "Philadelphia",
"State": "PA",
"EMail": "aaron_goodman@renovations.com"
}
If you only want to read FirstName and LastName, you can instead use this URL:
/xpagesext.nsf/api/data/documents/unid/39A95ECD82D0DEB485257AB5005BFEE0?fields=firstname,lastname
Now the response will look like this:
{
"@href": "/xpagesext.nsf/api/data/documents/unid/39A95ECD82D0DEB485257AB5005BFEE0",
"@unid": "39A95ECD82D0DEB485257AB5005BFEE0",
"@noteid": "5D26",
"@created": "2012-11-13T16:44:50Z",
"@modified": "2013-07-16T21:39:28Z",
"@form": "Contact",
"FirstName": "Aaron",
"LastName": "Goodman"
}
Data API view entries limit
The view entries resource GET operation now limits the number of entries returned in a response. This can potentially effect existing applications.
Suppose your API client requests 200 entries using this URL:
/xpagesext.nsf/api/data/collections/name/allcontacts?count=200
Prior to 9.0.1 FP8, the data API would return the specified number of entries (if available). As of 9.0.1 FP8, the data API will instead return HTTP 400 (Bad request):
{
"code": 400,
"text": "Bad Request",
"message": "Limit exceeded. Cannot read more than 100 entries."
}
IBM made this change to encourage paging through large views for better performance and scalability. However, if the change breaks existing applications, you can adjust the limit with a server notes.ini setting. For example, this setting increases the limit to 2000 entries:
DataServiceMaxViewEntries=2000
IBM recommends keeping the limit as low as possible. Ideally, you want each view entries request to complete quickly and you want your Domino server to be able to handle many simultaneous requests.
Meeting updates with the Calendar API
Prior to 9.0.1 FP8, it could be difficult to update a meeting with the calendar API because the calendar API enforced strict sequencing of updates. Consider this meeting in JSON format:
{
"events": [
{
"href": "/mail/dlawson.nsf/api/calendar/events/1D28F84D78AE721A852580EA005E4D07-Lotus_Auto_Generated",
"id": "1D28F84D78AE721A852580EA005E4D07-Lotus_Auto_Generated",
"summary": "Calendar API test",
"location": "test",
"description": "test\r\n",
"start": {
"date": "2017-04-01",
"time": "15:00:00",
"utc": true
},
"end": {
"date": "2017-04-01",
"time": "16:00:00",
"utc": true
},
"class": "public",
"transparency": "opaque",
"sequence": 5,
"last-modified": "20170321T171606Z",
"attendees": [
{
"role": "chair",
"status": "accepted",
"rsvp": false,
"displayName": "Duke Lawson/Renovations",
"email": "DukeLawson@renovations.com"
},
{
"role": "req-participant",
"status": "needs-action",
"rsvp": true,
"displayName": "Dean Melnyk/Renovations",
"email": "deanmelnyk@renovations.com"
}
],
"organizer": {
"displayName": "Duke Lawson/Renovations",
"email": "DukeLawson@renovations.com"
},
"x-lotus-broadcast": {
"data": "FALSE"
},
"x-lotus-notesversion": {
"data": "2"
},
"x-lotus-appttype": {
"data": "3"
}
}
]
}
Notice the value of the sequence property is 5. Now suppose you want to reschedule the meeting to a different time. You send a PUT request with a JSON representation of the update to this URL:
/mail/dlawson.nsf/api/calendar/events/1D28F84D78AE721A852580EA005E4D07-Lotus_Auto_Generated
But if you neglect to include the sequence property in your JSON input, versions of the API prior to 9.0.1 FP8 return HTTP 409 (Conflict):
{
"code": 409,
"text": "Conflict",
"cserror": 1027,
"message": "Error updating event",
"type": "text",
"data": "..."
}
Older versions of the API strictly enforce sequencing of updates to avoid unintended version conflicts, but this can complicate the implementation of your API client. As of 9.0.1 FP8, the calendar API relaxes the checking of sequence numbers. If for any reason you prefer the old behavior, you can add the strictsequence parameter to the PUT URL:
/mail/dlawson.nsf/api/calendar/events/1D28F84D78AE721A852580EA005E4D07-Lotus_Auto_Generated?strictsequence=true
Calendar API sincenow and days parameters
The event collection resource GET operation now supports sincenow and days parameters. These parameters make it simpler to request events in a date range relative to now.
Prior to 9.0.1 FP8, you could request a list of events in an absolute data range. For example, a GET request to the following URL returns all events in the month of April:
/mail/dlawson.nsf/api/calendar/events?since=2017-04-01T00:00:00Z&before=2017-05-01T00:00:00Z
As of 9.0.1 FP8, you can instead use the sincenow and days parameters to request events in a relative date range. The sincenow parameter specifies the start of the date range relative to now. The days parameter specifies the length of the date range.
For example, you can request events for the next 30 days:
/mail/dlawson.nsf/api/calendar/events?days=30
Or you can request 30 days of events starting 30 days after now:
/mail/dlawson.nsf/api/calendar/events?sincenow=30&days=30
Or you can request 60 days of events starting 30 days before now:
/mail/dlawson.nsf/api/calendar/events?sincenow=-30&days=60
Core API statistics resource
The DAS core API now includes a statistics resource. This resource represents DAS usage statistics on your Domino server. It groups API requests by category (e.g. calendarReadEvent, calendarUpdateEvent, dataViewEntryCollections, etc.). For each category it tracks the:
- total number of requests
- total time (in milliseconds) for all requests
- average time (in milliseconds) for all requests
To read the statistics resource, you send a GET request to:
/api/core/stats
The response looks something like this:
{
"calendarReadEventAvgRequestTime": 78,
"calendarReadEventRequestTime": 156,
"calendarReadEventRequests": 2,
"calendarTotalAvgRequestTime": 231,
"calendarTotalRequestTime": 2545,
"calendarTotalRequests": 11,
"calendarUpdateEventAvgRequestTime": 250,
"calendarUpdateEventRequestTime": 250,
"calendarUpdateEventRequests": 1,
"calendarViewEventsAvgRequestTime": 267,
"calendarViewEventsCount10_to_50": 6,
"calendarViewEventsCountUnder_10": 2,
"calendarViewEventsRequestTime": 2139,
"calendarViewEventsRequests": 8,
"coreTotalAvgRequestTime": 7,
"coreTotalRequestTime": 78,
"coreTotalRequests": 10,
"dataDbCollectionAvgRequestTime": 149,
"dataDbCollectionRequestTime": 749,
"dataDbCollectionRequests": 5,
"dataDocCollectionAvgRequestTime": 24,
"dataDocCollectionRequestTime": 6623,
"dataDocCollectionRequests": 268,
"dataDocumentAvgRequestTime": 19,
"dataDocumentRequestTime": 37601,
"dataDocumentRequests": 1911,
"dataTotalAvgRequestTime": 20,
"dataTotalRequestTime": 60249,
"dataTotalRequests": 2896,
"dataViewCollectionAvgRequestTime": 15,
"dataViewCollectionRequestTime": 46,
"dataViewCollectionRequests": 3,
"dataViewDesignAvgRequestTime": 2,
"dataViewDesignRequestTime": 16,
"dataViewDesignRequests": 6,
"dataViewEntryCollectionAvgRequestTime": 25,
"dataViewEntryCollectionRequestTime": 15151,
"dataViewEntryCollectionRequests": 601,
"dataViewEntryRequestTime": 31,
"dataViewEntryRequests": 45,
"totalAvgRequestTime": 21,
"totalRequestTime": 62872,
"totalRequests": 2924
}
OpenAPI Specifications on GitHub
Although not technically part of 9.0.1 FP8, IBM has simultaneously been working set of OpenAPI specifications for the DAS APIs. These specifications are now available in a new repository on GitHub:
https://github.com/OpenNTF/das-api-specs
These specifications represent DAS APIs in the industry standard OpenAPI format. You can use the specifications with a broad range of Swagger tools.